Writing a fully referenced paper
using Quarto / RMD & {citr}

Daniel Weiand, Consultant medical microbiologist

Newcastle upon Tyne Hospitals NHS Foundation Trust

November 17, 2022

Why use Quarto / RMD for academic writing?


On the one hand…

"The hardest part is starting. Once you get that out of the way, you'll find the rest of the journey much easier"

-- Simon Sinek


… And on the other

"Many will start fast, few will finish strong"

-- Gary Ryan Blair


Finishing a project is often the hardest part

Maximising the potential of Quarto / RMD & {citr}

Where to begin?

  1. Install Zotero

    • Create .bib file with academic references 1
  1. Download journal-specific Citation Style Language (.csl) file 2
  1. Optional: Create .docx reference-doc 3
  1. Optional: Create .css file 4
  1. Set YAML / knitr options settings 5
  1. Install {citr}6

Where to begin?

Then signpost your .bib, .csl, .docx., and .css files in your YAML 7 8


output: 
  word_document: 
    reference_docx: analysis_article_template.docx

bibliography: biblio.bib

csl: bmj.csl

css: mystyle.css

link-citations: true

Where to begin

Don’t forget to e.g. load your packages and select appropriate knitr options


#Project setup
options(scipen = 1, digits = 3)
ggplot2::theme_set(ggplot2::theme_minimal())

#Package load
library(citr)
library(tidyverse)
library(here)
library(flextable)
library(AMR)

#knitr options
knitr::opts_chunk$set(dev='jpeg', 
                      dpi = 300, 
                      fig.path = 'figures/',
                      fig.width = 6, 
                      fig.asp = 0.618, 
                      fig.align = 'center', 
                      out.width = "70%", 
                      cache.path = 'cache/',
                      cache = FALSE)

Adding citations

You can cite references listed in the .bib file, signposted in the YAML


For example, we may wish to cite the following paper by Anhøj et al.


Adding citations

Conventionally, citations need to be manually typed inside square brackets:


Blah blah [@anhoj2014run].
@anhoj2014run says blah.
Blah blah [see @anhoj2014run].

Adding citations

Instead, with {citr} you can simply click on the Addins button in RStudio


Adding citations

Click on insert citations


Adding citations

And use the free-text box to fuzzy search by author / date / title / journal & click insert citation


Cross-referencing functionality (Quarto)

For example, the following code …


@fig-airquality further explores the impact of temperature on ozone level.


… can be used to cross-reference to the following figure


##| label: fig-airquality
##| fig-cap: Temperature and ozone level.
##| warning: false

library(ggplot2)

ggplot(airquality, aes(Temp, Ozone)) + 
  geom_point() + 
  geom_smooth(method = "loess")

Cross-referencing functionality (Quarto)

Figure 1 further explores the impact of temperature on ozone level.

Figure 1: Temperature and ozone level.

References

Add a div with the id {#refs} at the location in your document where you’d like the bibliography to be generated.


# References

::: {#refs}
:::

Thank you for listening

Daniel Weiand, Consultant medical microbiologist

Newcastle upon Tyne Hospitals NHS Foundation Trust

Email: dweiand@nhs.net

NHS-R community blog: https://nhsrcommunity.com/author/daniel-weiand/

Twitter: @send2dan

Footnotes

  1. The Better BibTeX (BBT) extension for Zotero makes it easier to manage bibliographic data using markdown

  2. Search the Zotero style library for .csl files

  3. Use MS Word to set the Style of e.g. headings in the reference-doc

  4. .css files can be used for additional formatting (e.g. add double spacing to the final, rendered document)

  5. See my recent blog posts for further information on some of the differences in YAML requirements between .qmd (Quarto) and .rmd (RMarkdown)

  6. The {citr}package is not currently available on CRAN; install it through GitHub

  7. the files referred to in the YAML should be located in the main project directory

  8. Choosing link-citations: yes option will make your citations hyperlinks to the corresponding bibliography entries.